---
title: Tooltip
description: Tooltip displays a description of an element on hover or focus.
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/Tooltip.html
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/overlays/tooltip.mdx?plain=1
---

<ComponentPreview
  name="tooltip/demos/default"
  preview={`<Tooltip content={<span>Create new issue <Kbd>C</Kbd></span>}>
    <Button shape="square">
      <SquarePenIcon />
    </Button>
  </Tooltip>`}
/>

## Installation

```package-install
npx shadcn@latest add @dotui/tooltip
```

## Anatomy

```tsx
import { Tooltip } from "@/components/core/tooltip";

<Tooltip content="Edit">
  <Button>
    <EditIcon />
  </Button>
</Tooltip>;
```

```tsx
import { TooltipContent, TooltipRoot } from "@/components/core/tooltip";

<TooltipRoot>
  <Button>
    <EditIcon />
  </Button>
  <TooltipContent>
    <p>Edit</p>
  </TooltipContent>
</TooltipRoot>;
```

## Usage

Use `Tooltip` to display a description of an element on hover or focus.

### Best practices

- Use tooltips to describe icons (e.g., icon buttons).
- Keep the tooltip text minimal.
- Never include tooltips on non-interactive components (div, span, p) because it will not be accessible for keyboard or screen reader users.
- Don't place actions inside a tooltip (use Popover instead)

## Options

### Variant

Use the `variant` prop to change the appearance of the tooltip.

<ComponentPreview
  name="tooltip/demos/variant"
  preview={`<Tooltip variant="inverse" content="Create new issue">
    <Button shape="square">
      <SquarePenIcon />
    </Button>
  </Tooltip>`}
/>

### Placement

The Tooltip's placement with respect to its trigger element can be adjusted using the `placement` prop. See the props table for a full list of available placement combinations.

<ComponentPreview
  name="tooltip/demos/placement"
  preview={`<Tooltip placement="top" content="Create new issue"><Button /></Tooltip>
<Tooltip placement="bottom" content="Create new issue"><Button /></Tooltip>
<Tooltip placement="left" content="Create new issue"><Button /></Tooltip>
<Tooltip placement="right" content="Create new issue"><Button /></Tooltip>`}
/>

### Delay

The delay duration (the time from when the mouse enters a tooltip trigger until the tooltip opens) and the close delay can be customised.

<ComponentPreview
  name="tooltip/demos/delay"
  preview={`<Tooltip delay={delay} closeDelay={closeDelay} content="Create new issue">
    <Button>
      <PenIcon />
    </Button>
  </Tooltip>`}
/>

### Arrow

Use the `showArrow` prop to add an arrow to the tooltip.

<ComponentPreview
  name="tooltip/demos/arrow"
  preview={`<Tooltip content="Create new issue" arrow>
    <Button>
      <PenIcon />
    </Button>
  </Tooltip>`}
/>

### Should flip

This option determines whether or not a tooltip should be able to switch sides when constrained by space.

<ComponentPreview
  name="tooltip/demos/flip"
  preview={`<Tooltip shouldFlip={shouldFlip} content="Create new issue">
    <Button>
      <PenIcon />
    </Button>
  </Tooltip>`}
/>

### Offset

The offset is the distance between the end of the tip and the target.

<ComponentPreview
  name="tooltip/demos/offset"
  preview={`<Tooltip offset={offset} content="Create new issue">
    <Button>
      <PenIcon />
    </Button>
  </Tooltip>`}
/>

### Container padding

To make sure that the tooltip will stay within certain boundaries (e.g., a browser window) it's possible to define a container and a container padding value to respect. The default value for this is 12 px.

<ComponentPreview
  name="tooltip/demos/container-padding"
  preview={`<Tooltip containerPadding={containerPadding} content="Create new issue">
    <Button>
      <PenIcon />
    </Button>
  </Tooltip>`}
/>

## Composition

For more flexibility, you can drop down to the composition level.

<ComponentPreview
  name="tooltip/demos/composition"
  preview={`<TooltipRoot>
    <Button>Hover</Button>
    <TooltipContent>
      <p>Create new issue</p>
    </TooltipContent>
  </TooltipRoot>`}
/>

## API Reference

### Tooltip

| Prop                  | Type              | Default                                                                                              | Description                                                                                                                                                                            |
| --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`             | `React.ReactNode` | -                                                                                                    | The content of the Tooltip                                                                                                                                                             |
| `isDisabled`          | `boolean`         | -                                                                                                    | Whether the tooltip should be disabled, independent from the trigger.                                                                                                                  |
| `delay`               | `number`          | 700                                                                                                  | The delay time for the tooltip to show up.                                                                                                                                             |
| `closeDelay`          | `number`          | 0                                                                                                    | The delay time for the tooltip to close.                                                                                                                                               |
| `trigger`             | `'focus'`         | -                                                                                                    | By default, opens for both focus and hover. Can be made to open only for focus.                                                                                                        |
| `isOpen`              | `boolean`         | -                                                                                                    | Whether the overlay is open by default (controlled).                                                                                                                                   |
| `defaultOpen`         | `boolean`         | -                                                                                                    | Whether the overlay is open by default (uncontrolled).                                                                                                                                 |
| `triggerRef`          | `boolean`         | `RefObject<Element>`                                                                                 | The ref for the element which the tooltip positions itself with respect to.<br/>When used within a TooltipTrigger this is set automatically. It is only required when used standalone. |
| `isEntering`          | `boolean`         | -                                                                                                    | Whether the tooltip is currently performing an entry animation.                                                                                                                        |
| `isExiting`           | `boolean`         | -                                                                                                    | Whether the tooltip is currently performing an exit animation.                                                                                                                         |
| `placement`           | `Placement`       | `'top'`                                                                                              | The placement of the element with respect to its anchor element.                                                                                                                       |
| `containerPadding`    | `number`          | `12`                                                                                                 | The placement padding that should be applied between the element and its surrounding container.                                                                                        |
| `offset`              | `number`          | `10`                                                                                                 | The additional offset applied along the main axis between the element and its anchor element.                                                                                          |
| `crossOffset`         | `number`          | `0`                                                                                                  | The additional offset applied along the cross axis between the element and its anchor element.                                                                                         |
| `shouldFlip`          | `boolean`         | `true`                                                                                               | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.                                     |
| `isOpen`              | `boolean`         | -                                                                                                    | Whether the element is rendered.                                                                                                                                                       |
| `defaultOpen`         | `boolean`         | -                                                                                                    | Whether the overlay is open by default (uncontrolled).                                                                                                                                 |
| `arrowBoundaryOffset` | `number`          | -                                                                                                    | The minimum distance the arrow's edge should be from the edge of the overlay element.                                                                                                  |
| `children`            | `boolean`         | `ReactNode \| (values: TooltipRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | The children of the component. A function may be provided to alter the children based on component state.                                                                              |

| Event          | Type                        | Description                                                   |
| -------------- | --------------------------- | ------------------------------------------------------------- |
| `onOpenChange` | `(isOpen: boolean) => void` | Handler that is called when the overlay's open state changes. |

## Accessibility

### Keyboard interactions

| Key   | Description                                                                                         |
| ----- | --------------------------------------------------------------------------------------------------- |
| `Tab` | Tabbing into an item that has a tooltip associated with it (e.g., a button icon) shows the tooltip. |
| `Esc` | Hides the tooltip                                                                                   |
